On the Mac OS platform, most OpenDoc user documentation will be provided by Apple Guide on-line help. Apple Guide version 2.1 includes new features that support OpenDoc.
Essentially, Apple Guide 2.1 will dynamically assemble a guide for the active OpenDoc process by combining the help written for the parts in the process. Process help will always include help for the OpenDoc shell because the shell is included in every OpenDoc process. (The shell displays the Document and Edit menus and provides basic behavior, such as opening a document, printing, saving drafts, pasting, etc.) For example, let’s say the active process is a document called Sales Report, which contains a text part, a spreadsheet part, and a chart part. Apple Guide 2.1 will dynamically generates a Sales Report Guide by combining help for
• the OpenDoc shell
• the text part
• the spreadsheet part
• the chart part
For more information about how Apple Guide 2.1 supports OpenDoc, see the document called AG 2.1/OpenDoc Features in this folder.
The OpenDoc Shell Guide
The OpenDoc shell guide is an Apple Guide database that provides basic OpenDoc information and help for tasks done in the OpenDoc shell. Its contents cover the following:
• step-by-step help for tasks done in the OpenDoc shell (e.g., “How do I create a document?,” “How do I add a part to a document?,” etc.)
Since the OpenDoc shell guide is written, distributed, and updated by Apple, it provides basic OpenDoc user documentation free to developers. Part guides need only cover the features that are unique to the parts. Users will get the OpenDoc shell guide with their OpenDoc system software. Once the shell guide is installed, its contents are available when the user requests help for any OpenDoc process.
Apple Guide help for OpenDoc parts—an overview
Providing help for a part is not too different from providing help for an application. Here's an overview:
• Write a guide that covers the features specific to your part. (You need not cover information already covered in the OpenDoc shell guide.)
• Add a 'prts' resource to the compiled guide file. (See the Apple Guide 2.1 ERS for detailed instructions.) The 'prts' resource associates the guide with one or more specific parts, so that its content appears in the help access window only when those parts are present in the active OpenDoc process.
• Your part installer should install the guide file in the Global Guide Files folder (inside the Extensions folder).
When your part is present in the active OpenDoc process, Apple Guide 2.1 will locate its help and display it in the access window, along with help for other parts in the process and the OpenDoc shell.
The OpenDoc Shell Guide and Sample Part Guide folders
The OpenDoc Shell Guide and Sample Part Guide folders contain both compiled guides and source files. To open and browse the guides, you can use the OpenGuide 1.2 application (in the OpenDoc Shell Guide folder).
To see the guides in an OpenDoc process guide, you’ll need to do the following (everything you need is on this CD):
1. Install Apple Guide 2.1.
2. Drag OpenDoc shell guide 1.0b7 and the 3D viewer guide1.0d1 into the Global Guide Files folder (inside the Extensions folder).
3. Create an OpenDoc document that includes the KickStartQuickDraw 3D Viewer part, a sample part included on this CD. (You can simply open a new document with the 3D viewer by double-clicking the viewer's stationery icon.)
4. Open the Guide menu and choose the item named for the OpenDoc document you just created. The guide's access window should include topic areas from both the OpenDoc shell guide and the 3D viewer.
Where can I get more information?
For more information about installing and using Apple Guide 2.1, see the contents of the Apple Guide 2.1 folder. For information about using Apple Guide 2.1 to develop help for OpenDoc should contact APDA, Apple's source for developer tools, at apda@applelink.apple.com. Also see the Apple Guide web site (http://www.macos.apple.com/Apple_Guide/) and the OpenDoc web site (http://www.opendoc.apple.com/).
